Requirements of the Comment API

Motivation#

In today's technological world, complex applications have emerged that have enhanced interaction between users across the globe. One example of such applications is the social media platforms where users post their content, including creative works consisting of images and videos. Such platforms allow users to comment on a post to provide feedback, additional information, suggestions, corrections, or appreciation. The process of creating a comment on a post is a complex system that involves the interaction of different components at different levels. Therefore, there is a need to design an API to interlink the communication of all the interacting components in the comment system.

In this lesson, we will focus on the requirements for designing the API for a comment service so that we will be able to perform various functions related to comments.

Introduction to the comment service API#

When a client intends to perform an action relevant to a comment—for example, creating, updating, or deleting a comment—a request is initiated and passed through the API gateway. The API gateway acts as a reverse proxy by routing requests from clients to services. It also provides some other preliminary features, including authorization, access control, cache, throttling limits, and so on.

Upon the successful completion (or unsuccessful attempt) of a received request at the backend, a response is generated and sent back to the client accordingly. The following figure abstracts the components involved in this process.

Requirements#

We will focus on the following necessary functional and non-functional requirements for an API to perform various comment operations.

Functional requirements#

Our API should allow the following functions to the users:

• Create a comment: The first operation that our proposed API should allow is to post a comment.

• Update a comment: The API should allow users to update or edit their comments after posting them.

• Get comment(s): The API should allow users to fetch comments from the back-end servers.

• Delete a comment: Users should be able to delete or remove a comment they posted.

• Flag comments: In case something violates the platform’s code of conduct, any user can flag a comment—be it the author of the resource where the comment was posted or a user reading the comment.

Note: For the sake of simplicity, we will refer to a resource where comments are posted as a “post.” Also, our design problem will only consider comments posted on public resources.

Non-functional requirements#

Our API should be able to adhere to the following non-functional requirements for smooth operations:

• Scalability: Our API should be able to handle an ever-increasing number of users commenting on different posts.

• Availability: Our API should be highly available to provide continuous service to users.

• Security: Our API should adopt the latest authorization and authentication mechanisms to provide secure services. Furthermore, it should also secure communication between clients and servers.

• Reliability: Our API should be highly reliable and operate correctly despite failures in one or more parts of the system.

• Low latency: Users should be able to see all publicly posted comments with low latency.

How will we design a comment API?#

We divided the design of API for a comment service into the following three lessons:

1. Comment API Design Decisions: In this lesson, we’ll highlight some important techniques and design decisions to model our API. In addition to different architectural styles, we will also discuss different data formats and HTTP versions to opt for the interaction between various components.

2. API Model for the Comment Service: This lesson discusses API architecture for a comment service. We will identify different endpoints and approaches to access resources and fulfill the aforementioned functional requirements.

3. Comment API Design Evaluation and Latency Budget: This lesson focuses on how we achieve the non-functional requirements. It also covers some important techniques that can enhance the effectiveness of our proposed API.

Let's start with the important design decisions that direct the design of our proposed API.